Path and Url procedures

Assorted path and url procedures.

Include file: AfxPath.inc

Path procedures

Url procedures

AfxPathAddBackSlash

Adds a backslash to the end of a string to create the correct syntax for a path. If the source path already has a trailing backslash, no backslash will be added.

FUNCTION AfxPathAddBackSlash (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The changed path.

Usage example

DIM dws AS DWSTRING = AfxPathAddBackSlash("C:\dir_name\dir_name\file_name")

AfxPathAddExtension

Adds a file name extension to a path string.

FUNCTION AfxPathAddExtension (BYREF wszPath AS CONST WSTRING, BYVAL pwszExt AS WSTRING PTR = NULL) AS DWSTRING

Return value

The changed path.

Remarks

If there is already a file name extension present, no extension will be added. If the wszPath is an empty string, the result will be the file name extension only. If wszExtension is an empty string, an “.exe” extension will be added.

Usage examples

DIM dws AS DWSTRING = AfxPathAddExtension("file") ' output: file.exe
DIM dws AS DWSTRING = AfxPathAddExtension("file.doc") ' output: file.doc
DIM dws AS DWSTRING = AfxPathAddExtension("file", ".txt") ' output: file.txt
DIM dws AS DWSTRING = AfxPathAddExtension("", ".txt") ' output: .txt

AfxPathAllocCanonicalize

Converts a path string into a canonical form. This function differs from AfxPathCanonicalize in that it accepts paths with “\”, “\?” and “\?\UNC” prefixes, as well as one or more flags.

FUNCTION AfxPathAllocCanonicalize (BYVAL pwszPathIn AS PCWSTR, BYVAL dwFlags AS ULONG) AS DWSTRING

Usage example

AfxPathAllocCanonicalize(ExePath, PATHCCH_ENSURE_TRAILING_SLASH)

AfxPathAllocCombine

Converts a path string into a canonical form. Concatenates two path fragments into a single path. This function also canonicalizes any relative path elements, replacing path elements such as “.” and “..”. This function differs from PathCombine in that it accepts paths with “\”, “\?” and “\?\UNC” prefixes.

FUNCTION AfxPathAllocCombine (BYVAL pwszPathIn AS PCWSTR, BYVAL pwszMore AS PCWSTR, _
   BYVAL dwFlags AS ULONG) AS DWSTRING

Usage example

AfxPathAllocCombine(ExePath, "Test", PATHCCH_ENSURE_TRAILING_SLASH)

AfxPathAppend

Appends one path to the end of another.

FUNCTION AfxPathAppend (BYREF wszPath AS CONST WSTRING, BYREF wszMore AS CONST WSTRING) AS DWSTRING

Return value

The changed path.

Remarks

This function automatically inserts a backslash between the two strings, if one is not already present.

The path supplied in wszPath cannot begin with “..\” or “.\” to produce a relative path string. If present, those periods are stripped from the output string. For example, appending “path3” to “..\path1\path2” results in an output of “\path1\path2\path3” rather than “..\path1\path2\path3”.

Usage example

DIM dws AS DWSTRING = AfxPathAppend("name_1\name_2", "name_3")

AfxPathBuildRoot

Creates a root path from a given drive number.

FUNCTION AfxPathBuildRoot (BYVAL nDrive AS LONG) AS DWSTRING

Return value

The root path. If the call fails for any reason (for example, an invalid drive number), an empty string is returned.

Usage example

DIM dws AS DWSTRING = AfxPathBuildRoot(2) ' output: C:\

AfxPathCanonicalize

Removes elements of a file path according to special strings inserted into that path.

FUNCTION AfxPathCanonicalize (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The canonicalized path.

Remarks

This function allows the user to specify what to remove from a path by inserting special character sequences into the path. The “..” sequence indicates to remove a path segment from the current position to the previous path segment. The “.” sequence indicates to skip over the next path segment to the following path segment. The root segment of the path cannot be removed.

If there are more “..” sequences than there are path segments, the contents of the returned string contains just the root, “\”.

Usage example

DIM dws AS DWSTRING = AfxPathCanonicalize("A:\name_1\.\name_2\..\sname_3") ' output: A:\name_1\name_3
DIM dws AS DWSTRING = AfxPathCanonicalize("A:\name_1\..\name_2\.\name_3") ' output: A:\name_2\name_3
DIM dws AS DWSTRING = AfxPathCanonicalize("A:\name_1\name_2\.\name_3\..\name_4") ' output: A:\name_1\name_2\name_4
DIM dws AS DWSTRING = AfxPathCanonicalize("A:\name_1\.\name_2\.\name_3\..\name_4\..") ' output: A:\name_1\name_2
DIM dws AS DWSTRING = AfxPathCanonicalize("C:\..") ' output: C:\

AfxPathCombine

Concatenates two strings that represent properly formed paths into one path; also concatenates any relative path elements.

FUNCTION AfxPathCombine (BYREF wszDir AS CONST WSTRING, BYREF wszFile AS CONST WSTRING) AS DWSTRING

Return value

The concatenated path if successful, or an empty string otherwise.

Remarks

The directory path should be in the form of A:,B:, …, Z:. The file path should be in a correct form that represents the file part of the path. The file path must not be null, and if it ends with a backslash, the backslash will be maintained.

Usage example

DIM dws AS DWSTRING = AfxPathCombine("C:", "One\Two\Three") ' output: C:\One\Two\Three

AfxPathCommonPrefix

Compares two paths to determine if they share a common prefix. A prefix is one of these types: “C:\”, “.”, “..”, “..\”.

FUNCTION AfxPathCommonPrefix (BYREF wszFile1 AS CONST WSTRING, BYREF wszFile2 AS CONST WSTRING) AS DWSTRING

Return value

The common prefix.

Usage example

DIM dws AS DWSTRING = AfxPathCommonPrefix("C:\win\desktop\temp.txt", "c:\win\tray\sample.txt")

AfxPathCompactPath

Truncates a file path to fit within a given pixel width by replacing path components with ellipses.

FUNCTION AfxPathCompactPath (BYVAL hDC AS HDC, BYREF wszPath AS CONST WSTRING, BYVAL dx AS DWORD) AS DWSTRING

Return value

The compacted path.

Remarks

This function uses the font currently selected in hDC to calculate the width of the text. This function will not compact the path beyond the base file name preceded by ellipses.

Usage example

DIM dws AS DWSTRING = AfxPathCompactPath(NULL, "C:\path1\path2\sample.txt", 180)

AfxPathCompactPathEx

Truncates a path to fit within a certain number of characters by replacing path components with ellipses.

FUNCTION AfxPathCompactPathEx (BYREF wszPath AS CONST WSTRING, BYVAL cchMax AS DWORD) AS DWSTRING

Return value

The compacted path.

Remarks

The ‘/’ separator will be used instead of ‘\’ if the original string used it. If wszPath points to a file name that is too long, instead of a path, the file name will be truncated to cchMax characters, including the ellipsis and the terminating NULL character. For example, if the input file name is “My Filename” and cchMax is 10, AfxPathCompactPathEx will return “My Fil…”.

Usage example

DIM dws AS DWSTRING = AfxPathCompactPathEx("c:\test\My Filename", 18)

AfxPathCreateFromUrl

Converts a file URL to a Microsoft MS-DOS path.

FUNCTION AfxPathCreateFromUrl (BYREF wszUrl AS CONST WSTRING) AS DWSTRING

Return value

The MS-DOS path.

Usage example

DIM dws AS DWSTRING = AfxPathCreateFromUrl("file:///C:/Documents%20and%20Settings/URIS.txt")

AfxPathFileExists

Determines whether a path to a file system object such as a file or directory is valid.

FUNCTION AfxPathFileExists (BYREF wszPath AS WSTRING) AS BOOLEAN

Return value

Returns TRUE if the file exists, or FALSE otherwise.

Remarks

This function tests the validity of the path.

A path specified by Universal Naming Convention (UNC) is limited to a file only; that is, \\server\shareis permitted. A UNC path to a server or server share is not permitted; that is, \\server or \\server\share. This function returns FALSE if a mounted remote drive is out of service.

AfxPathFindExtension

Searches a path for an extension.

FUNCTION AfxPathFindExtension (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The file name extension.

Remarks

Note that a valid file name extension cannot contain a space.

Usage example

DIM dws AS DWSTRING = AfxPathFindExtension("C:\TEST\filetxt")

AfxPathFindFileName

Searches a path for a file name.

FUNCTION AfxPathFindFileName (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The file name.

AfxPathFindNextComponent

Searches a path for a file name.

FUNCTION AfxPathFindNextComponent (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The truncated path.

Remarks

AfxPathFindNextComponent walks a path string until it encounters a backslash (“\”), ignores everything up to that point including the backslash, and returns the rest of the path. Therefore, if a path begins with a backslash (such as \path1\path2), the function simply removes the initial backslash and returns the rest (path1\path2).

Usage example

DIM dws AS DWSTRING = AfxPathFindNextComponent("C:\TEST\file.txt")

AfxPathFindOnPath

Searches for a file.

FUNCTION AfxPathFindOnPath (BYREF wszFile AS CONST WSTRING, _
   BYVAL ppwszOtherDirs AS WSTRING PTR PTR = NULL) AS DWSTRING

Return value

The fully-qualified path name on success or an empty string on failure.

Remarks

AfxPathFindOnPath searches for the file specified by wszFile. If no directories are specified in ppwszOtherDirs, it attempts to find the file by searching standard directories such as System32 and the directories specified in the PATH environment variable. To expedite the process or enable AfxPathFindOnPath to search a wider range of directories, use the ppwszOtherDirs parameter to specify one or more directories to be searched first. If more than one file has the name specified by wszFile, AfxPathFindOnPath returns the first instance it finds.

AfxPathFindSuffixArray

Determines whether a given file name has one of a list of suffixes.

FUNCTION AfxPathFindSuffixArray (BYREF wszPath AS WSTRING, BYVAL apwszSuffix AS WSTRING PTR PTR, _
   BYVAL iArraySize AS LONG) AS DWSTRING

Return value

The matching suffix if successful, or an empty string if bstrPath does not end with one of the specified suffixes.

Remarks

This function uses a case-sensitive comparison. The suffix must match exactly.

AfxPathGetArgs

Finds the command line arguments within a given path.

FUNCTION AfxPathGetArgs (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

A string that contains the arguments portion of the path if successful or an empty string if there are no arguments in the path.

Remarks

This function should not be used on generic command path templates (from users or the registry), but rather should be used only on templates that the application knows to be well formed.

AfxPathGetCharType

Determines the type of character in relation to a path.

FUNCTION AfxPathGetCharType (BYREF wszCh AS CONST WSTRING) AS UINT

Return value

Returns one or more of the following values that define the type of character.

AfxPathGetDriveNumber

Searches a path for a drive letter within the range of ‘A’ to ‘Z’ and returns the corresponding drive number.

FUNCTION AfxPathGetDriveNumber (BYREF wszPath AS CONST WSTRING) AS LONG

Return value

Returns 0 through 25 (corresponding to ‘A’ through ‘Z’) if the path has a drive letter, or -1 otherwise.

Usage example

DIM n AS LONG = AfxPathGetDriveNumber("C:\TEST\bar.txt") ' output: 2

AfxPathIsContentType

Determines if a file’s registered content type matches the specified content type. This function obtains the content type for the specified file type and compares that string with the wszContentType. The comparison is not case-sensitive.

FUNCTION AfxPathIsContentType (BYREF wszPath AS CONST WSTRING, _
   BYREF wszContentType AS CONST WSTRING) AS BOOLEAN

Return value

Returns nonzero if the file’s registered content type matches wszContentType, or zero otherwise.

Usage example

DIM b AS BOOLEAN = AfxPathIsContentType("C:\TEST\bar.txt", "text/plain") ' output: true
DIM b AS BOOLEAN = AfxPathIsContentType("C:\TEST\bar.txt", "image/gif") ' output: false

AfxPathIsDirectory

Verifies that a path is a valid directory.

FUNCTION AfxPathIsDirectory (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns TRUE if the path is a valid directory (FILE_ATTRIBUTE_DIRECTORY is set), or FALSE otherwise.

AfxPathIsDirectoryEmpty

Determines whether a specified path is an empty directory.

FUNCTION AfxPathIsDirectoryEmpty (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns TRUE if wszPath is an empty directory. Returns FALSE if wszPath is not a directory, or if it contains at least one file other than “.” or “..”.

Remarks

“C:" is considered a directory.

AfxPathIsFileSpec

Searches a path for any path-delimiting characters (for example, ‘:’ or ‘\’ ). If there are no path-delimiting characters present, the path is considered to be a File Spec path.

FUNCTION AfxPathIsFileSpec (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns TRUE if there are no path-delimiting characters within the path, or FALSE if there are path-delimiting characters.

AfxPathIsHTMLFile

Determines if a file is an HTML file. The determination is made based on the content type that is registered for the file’s extension.

FUNCTION AfxPathIsHTMLFile (BYREF wszFile AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the file is an HTML file, or False otherwise.

AfxPathIsLFNFileSpec

Determines whether a file name is in long format.

FUNCTION AfxPathIsLFNFileSpec (BYREF wszName AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if wszName exceeds the number of characters allowed by the 8.3 format, or False otherwise.

AfxPathIsNetworkPath

Determines whether a path string represents a network resource.

FUNCTION AfxPathIsNetworkPath (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the string represents a network resource, or False otherwise.

AfxPathIsPrefix

Searches a path to determine if it contains a valid prefix of the type passed by wszPrefix. A prefix is one of these types: “C:\”, “.”, “..”, “..\”.

FUNCTION AfxPathIsPrefix (BYREF wszPrefix AS CONST WSTRING, BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the compared path is the full prefix for the path, or False otherwise.

AfxPathIsRelative

Searches a path and determines if it is relative.

FUNCTION AfxPathIsRelative (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the path is relative, or False if it is absolute.

AfxPathIsRoot

Parses a path to determine if it is a directory root.

FUNCTION AfxPathIsRoot (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the specified path is a root, or False otherwise.

Remarks

Returns True for paths such as “\”, “X:\” or “\\server\share”. Paths such as “..\path2” or “\\server\” return FALSE.

AfxPathIsSameRoot

Compares two paths to determine if they have a common root component.

FUNCTION AfxPathIsSameRoot (BYREF wszPath1 AS CONST WSTRING, BYREF wszPath2 AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if both strings have the same root component, or False otherwise. If wszPath1 contains only the server and share, this function also returns False.

AfxPathIsSystemFolder

Determines if an existing folder contains the attributes that make it a system folder. Alternately, this function indicates if certain attributes qualify a folder to be a system folder.

FUNCTION AfxPathIsSystemFolder (BYREF wszPath AS CONST WSTRING, BYVAL dwAttrb AS DWORD) AS BOOLEAN

Return value

Returns True if the wszPath or dwAttrb represent a system folder, or False otherwise.

AfxPathIsUNC

Determines if the string is a valid Universal Naming Convention (UNC) for a server and share path.

FUNCTION AfxPathIsUNC (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the string is a valid UNC path, or False otherwise.

AfxPathIsUNCServer

Determines if a string is a valid Universal Naming Convention (UNC) for a server path only.

FUNCTION AfxPathIsUNCServer (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the string is a valid UNC path for a server only (no share name), or False otherwise.

AfxPathIsUNCServerShare

Determines if a string is a valid Universal Naming Convention (UNC) share path, \\server\share.

FUNCTION AfxPathIsUNCServerShare (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the string is in the form \\server\share, or False otherwise.

AfxPathIsURL

Tests a given string to determine if it conforms to a valid URL format.

FUNCTION AfxPathIsURL (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if wszPath has a valid URL format, or Fañse otherwise.

Remarks

This function does not verify that the path points to an existing site—only that it has a valid URL format.

AfxPathMakePretty

Converts a path to all lowercase characters to give the path a consistent appearance.

FUNCTION AfxPathMakePretty (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The changed path.

Remarks

This function only operates on paths that are entirely uppercase. For example: C:will be converted to c:, but c:will not be changed.

AfxPathMakeSystemFolder

Gives an existing folder the proper attributes to become a system folder.

FUNCTION AfxPathMakeSystemFolder (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if successful, or False otherwise.

AfxPathMatchSpec

Searches a string using a Microsoft MS-DOS wild card match type.

FUNCTION AfxPathMatchSpec (BYREF wszFile AS CONST WSTRING, BYREF wszSpec AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the string matches, or False otherwise.

AfxPathMatchSpecEx

Searches a path to determine whether it contains a file of a specified file type extension.

FUNCTION AfxPathMatchSpecEx (BYREF wszFile AS CONST WSTRING, _
   BYREF wszSpec AS CONST WSTRING, BYVAL dwFlags AS DWORD) AS BOOLEAN

Return value

Returns one of the following values:

AfxPathParseIconLocation

Parses a file location string that contains a file location and icon index, and returns separate values.

FUNCTION AfxPathParseIconLocation (BYREF wszIconFile AS CONST WSTRING) AS DWSTRING

Return value

Returns the valid icon index value.

Remarks

This function is useful for taking a DefaultIcon value retrieved from the registry by SHGetValue and separating the icon index from the path.

Usage example

DIM dwsIconLocation AS DWSTRING = AfxPathParseIconLocation("C:\TEST\sample.txt,3")

AfxPathQuoteSpaces

Searches a path for spaces. If spaces are found, the entire path is enclosed in quotation marks.

FUNCTION AfxPathQuoteSpaces (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

True if spaces were found; otherwise, False.

AfxPathRelativePathTo

Creates a relative path from one file or folder to another.

FUNCTION AfxPathRelativePathTo (BYREF wszFrom AS CONST WSTRING, BYVAL dwAttrFrom AS DWORD, _
   BYREF wszTo AS CONST WSTRING, BYVAL dwAttrTo AS DWORD) AS DWSTRING

Return value

Returns True if successful, or False otherwise.

Remarks

This function takes a pair of paths and generates a relative path from one to the other. The paths do not have to be fully-qualified, but they must have a common prefix, or the function will fail and return False.

For example, let the starting point, wszFrom, be “c:\FolderA\FolderC”, and the ending point, wszTo, be “c:\FolderA\FolderD\FolderE”. AfxPathRelativePathTo will return the relative path from wszFrom to wszTo as: “..\..\FolderD\FolderE”. You will get the same result if you set wszFrom to “\FolderA\FolderB\FolderC” and wszTo to “\FolderA\FolderD\FolderE”. On the other hand, “c:\FolderA\FolderB” and “a:\FolderA\FolderD do not share a common prefix, and the function will fail. Note that”\\” is not considered a prefix and is ignored. If you set wszFrom to “\\FolderA\FolderB”, and wszTo to “\\FolderC\FolderD”, the function will fail.

AfxPathRemoveArgs

Removes any arguments from a given path.

FUNCTION AfxPathRemoveArgs (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The changed path.

Remarks

This function should not be used on generic command path templates (from users or the registry), but rather it should be used only on templates that the application knows to be well formed.

AfxPathRemoveBackslash

Removes the trailing backslash from a given path.

FUNCTION AfxPathRemoveBackslash (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The changed path. If no trailing backslash was found, the string is unchanged.

Usage example

DIM dws AS DWSTRING = AfxPathRemoveBackslash("c:\a\b\File\")

AfxPathRemoveBackslashEx

Removes the trailing backslash from a given path. This function differs from PathRemoveBackslash in that it accepts paths with “\”, “\?” and “\?\UNC” prefixes.

FUNCTION AfxPathRemoveBackslashEx (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The changed path. If no trailing backslash was found, the string is unchanged.

Usage example

DIM dws AS DWSTRING = AfxPathRemoveBackslashEx("c:\a\b\File\")

AfxPathRemoveBlanks

Removes all leading and trailing spaces from a string.

FUNCTION AfxPathRemoveBlanks (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The changed path.

AfxPathRemoveExtension

Removes the file name extension from a path, if one is present.

FUNCTION AfxPathRemoveExtension (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The changed path.

AfxPathRemoveFileSpec

Removes the trailing file name and backslash from a path, if they are present.

FUNCTION AfxPathRemoveFileSpec (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The changed path.

AfxPathRenameExtension

Replaces the extension of a file name with a new extension. If the file name does not contain an extension, the extension will be attached to the end of the string.

FUNCTION AfxPathRenameExtension (BYREF wszPath AS CONST WSTRING, BYREF wszExt AS CONST WSTRING) AS DWSTRING

Return value

The new path. If the new path and extension would exceed MAX_PATH characters, the path won’t be changed.

AfxPathSearchAndQualify

Determines if a given path is correctly formatted and fully qualified.

FUNCTION AfxPathSearchAndQualify (BYREF wszPath AS CONST WSTRING, BYREF wszFullyQualifiedPath AS CONST WSTRING, _
   BYVAL cchFullyQualifiedPath AS DWORD) AS BOOLEAN

Return value

Returns True if the path is qualified, or False otherwise.

AfxPathSetDlgItemPath

Sets the text of a child control in a window or dialog box, using AfxCompactPath to ensure the path fits in the control.

SUB AfxPathSetDlgItemPath (BYVAL hDlg AS HWND, BYVAL cID AS LONG, BYREF wszPath AS WSTRING)

AfxPathSkipRoot

Parses a path, ignoring the drive letter or Universal Naming Convention (UNC) server/share path elements.

FUNCTION AfxPathSkipRoot (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The changed path.

AfxPathStripPath

Removes the path portion of a fully qualified path and file.

FUNCTION AfxPathStripPath (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The changed path.

AfxPathStripToRoot

Removes all parts of the path except for the root information.

FUNCTION AfxPathStripToRoot (BYREF wszRoot AS CONST WSTRING) AS DWSTRING

Return value

Returns a string that contains only the root information taken from that path.

AfxPathUndecorate

Removes the decoration from a path string.

FUNCTION AfxPathUndecorate (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The undecorated string.

Remarks

A decoration consists of a pair of square brackets with one or more digits in between, inserted immediately after the base name and before the file name extension.

Example

The following table illustrates how strings are modified by AfxPathUndecorate.

AfxPathUnExpandEnvStrings

Replaces certain folder names in a fully-qualified path with their associated environment string.

FUNCTION AfxPathUnExpandEnvStrings (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The unexpanded string.

AfxPathUnmakeSystemFolder

Removes the attributes from a folder that make it a system folder. This folder must actually exist in the file system.

FUNCTION AfxPathUnmakeSystemFolder (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns nonzero if successful, or zero otherwise.

AfxPathUnquoteSpaces

Removes quotes from the beginning and end of a path.

FUNCTION AfxPathUnquoteSpaces (BYREF wszPath AS CONST WSTRING) AS DWSTRING

Return value

The unquoted path.

AfxIsValidUrl

Determines if a specified string is a valid URL.

FUNCTION AfxIsValidUrl (BYREF wszUrl AS CONST WSTRING) AS BOOLEAN

Remarks

Return True if the URL is valid; FALSE, otherwise.

AfxUrlApplyScheme

Determines a scheme for a specified URL string, and returns a string with an appropriate prefix.

FUNCTION AfxUrlApplyScheme (BYREF wszUrl AS WSTRING, BYVAL dwFlags AS DWORD) AS DWSTRING

Return value

The changed url.

Remarks

If the URL has a valid scheme, the string will not be modified. However, almost any combination of two or more characters followed by a colon will be parsed as a scheme. Valid characters include some common punctuation marks, such as “.”. If your input string fits this description, AfxUrlApplyScheme may treat it as valid and not apply a scheme. To force the function to apply a scheme to a URL, set the URL_APPLY_FORCEAPPLY and URL_APPLY_DEFAULT flags in dwFlags. This combination of flags forces the function to apply a scheme to the URL. Typically, the function will not be able to determine a valid scheme. The second flag guarantees that, if no valid scheme can be determined, the function will apply the default scheme to the URL.

AfxUrlCanonicalize

Converts a URL string into canonical form.

FUNCTION AfxUrlCanonicalize (BYREF wszUrl AS WSTRING, BYVAL dwFlags AS DWORD) AS DWSTRING

Return value

The canonicalized url.

Remarks

This function performs such tasks as replacing unsafe characters with their escape sequences and collapsing sequences like “..\…”.

If a URL string contains “/../” or “/./”, AfxUrlCanonicalize normally treats the characters as indicating navigation in the URL hierarchy. The function simplifies the URLs before combining them. For instance “/hello/cruel/../world” is simplified to “/hello/world”. If the URL_DONT_SIMPLIFY flag is set in dwFlags, the function does not simplify URLs. In this case, “/hello/cruel/../world” is left as it is.

AfxUrlCombine

When provided with a relative URL and its base, returns a URL in canonical form.

FUNCTION AfxUrlCombine (BYREF wszBase AS WSTRING, BYREF wszRelative AS WSTRING, BYVAL dwFlags AS DWORD) AS DWSTRING

Return value

The canonicalized url.

Remarks

Items between slashes are treated as hierarchical identifiers; the last item specifies the document itself. You must enter a slash (/) after the document name to append more items; otherwise, AfxUrlCombine changes one document for another.

If a URL string contains ‘/../’ or ‘/./’, AfxUrlCombine usually treats the characters as if they indicated navigation in the URL hierarchy. The function simplifies the URLs before combining them. For instance, “/hello/cruel/../world” is simplified to “/hello/world”. If the URL_DONT_SIMPLIFY flag is set in dwFlags, the function does not simplify URLs. In this case, “/hello/cruel/../world” is left as it is.

AfxUrlCompare

Makes a case-sensitive comparison of two URL strings.

FUNCTION AfxUrlCompare (BYREF wszUrl1 AS CONST WSTRING, BYREF wszUrl2 AS CONST WSTRING, _
   BYVAL fIgnoreSlash AS LONG) AS LONG

Return value

Returns zero if the two strings are equal. The function will also return zero if fIgnoreSlash is set to TRUE and one of the strings has a trailing ‘\’ character. The function returns a negative integer if the string pointed to by wszUrl1 is less than the string pointed to by wszUrl2. Otherwise, it returns a positive integer.

Remarks

For best results, you should first canonicalize the URLs with AfxUrlCanonicalize. Then, compare the canonicalized URLs with AfxUrlCompare.

AfxUrlCreateFromPath

Converts a Microsoft MS-DOS path to a canonicalized URL.

FUNCTION AfxUrlCreateFromPath (BYREF wszPath AS WSTRING) AS DWSTRING

Return value

The canonicalized URL.

AfxUrlEscape

Converts characters in a URL that might be altered during transport across the Internet (“unsafe” characters) into their corresponding escape sequences.

FUNCTION AfxUrlEscape (BYREF wszUrl AS WSTRING, BYVAL dwFlags AS DWORD) AS DWSTRING

Return value

The converted URL.

Remarks

For the purposes of this document, a typical URL is divided into three sections: the server, the segment, and the query. For example:

http://microsoft.com/test.asp?url=/example/abc.asp?frame=true#fragment

The server portion is “http://microsoft.com/”. The trailing forward slash is considered part of the server portion.

The segment portion is any part of the path found following the server portion, but before the first # or ? character, in this case simply “test.asp”.

The query portion is the remainder of the path from the first # or ? character (inclusive) to the end. In the example, it is “?url=/example/abc.asp?frame=true#fragment”.

Unsafe characters are those characters that might be altered during transport across the Internet. This function converts unsafe characters into their equivalent “%xy” escape sequences. The following table shows unsafe characters and their escape sequences.

Use of the URL_ESCAPE_SEGMENT_ONLY flag also causes the conversion of the # (%23), ? (%3F), and / (%2F) characters.

By default, AfxUrlEscape ignores any text following a # or ? character. The URL_ESCAPE_SEGMENT_ONLY flag overrides this behavior by regarding the entire string as the segment. The URL_ESCAPE_SPACES_ONLY flag overrides this behavior, but only for space characters.

Security Warning: This function should be called from client applications only.

AfxUrlEscapeSpaces

Converts space characters into their corresponding escape sequence.

FUNCTION AfxUrlEscapeSpaces (BYREF wszUrl AS WSTRING) AS DWSTRING

Return value

The converted URL.

AfxUrlFixup

Attempts to correct a URL whose protocol identifier is incorrect. For example, htttp will be changed to http.

FUNCTION AfxUrlFixup (BYREF wszUrl AS WSTRING) AS DWSTRING

Return value

The converted URL.

Remarks

The AfxUrlFixup function recognizes the schemes specified by the URL_SCHEME enumeration.

Priority is given to the first character in the protocol identifier section so htp will be converted to http instead of ftp.

Notes

Do not use this function for deterministic data transformation. The heuristics used by AfxUrlFixup can change from one release to the next. The function should only be used to correct possibly invalid user input.

This function is available through Windows 7 and Windows Server 2008. It might be altered or unavailable in subsequent versions of Windows.

AfxUrlGetHostName

Accepts a URL string and returns the host name.

FUNCTION AfxUrlGetHostName (BYREF wszUrl AS CONST WSTRING) AS DWSTRING

Return value

If the function succeeds, it returns the host name; if it fails, it returns an empty string.

Usage example

print AfxUrlGetHostName("https://user@example.com:8080/path/to/resource?id=123&lang=es")

AfxUrlGetLocation

Retrieves the location from a URL.

FUNCTION AfxUrlGetLocation (BYREF wszUrl AS CONST WSTRING) AS DWSTRING

Return value

A string with the location or an empty string.

Remarks

The location is the segment of the URL starting with a ? or # character. If a file URL has a query string, the returned string includes the query string.

AfxUrlGetPart

Accepts a URL string and returns a specified part of that URL.

FUNCTION AfxUrlGetPart (BYREF wszUrl AS WSTRING, _
   BYVAL dwPart AS DWORD, BYVAL dwFlags AS DWORD) AS DWSTRING

Return value

A string with the specified part of that URL.

AfxUrlGetPassword

Accepts a URL string and returns the password.

FUNCTION AfxUrlGetPassword (BYREF wszUrl AS CONST WSTRING) AS DWSTRING

Return value

If the function succeeds, it returns the password; if it fails, it returns an empty string.

Usage example

print AfxUrlGetPassword("https://user:secret@example.com:8080/path/to/resource?id=123&lang=es")

AfxUrlGetPort

Accepts a URL string and returns the port number.

FUNCTION AfxUrlGetPort (BYREF wszUrl AS CONST WSTRING) AS DWSTRING

Return value

If the function succeeds, it returns the port number; if it fails, it returns an empty string.

Usage example

print AfxUrlGetPassword("https://user:secret@example.com:8080/path/to/resource?id=123&lang=es")

AfxUrlGetQuery

Accepts a URL string and returns the query portion.

FUNCTION AfxUrlGetQuery (BYREF wszUrl AS CONST WSTRING) AS DWSTRING

Return value

If the function succeeds, it returns the query portion; if it fails, it returns an empty string.

Usage example

print AfxUrlGetQuery("https://user@example.com:8080/path/to/resource?id=123&lang=es")

AfxUrlGetSchema

Accepts a URL string and returns the scheme.

FUNCTION AfxUrlGetScheme (BYREF wszUrl AS CONST WSTRING) AS DWSTRING

Return value

If the function succeeds, it returns the scheme; if it fails, it returns an empty string.

Usage example

print AfxUrlGetScheme("https://user@example.com:8080/path/to/resource?id=123&lang=es")

AfxUrlGetUserName

Accepts a URL string and returns the user name.

FUNCTION AfxUrlGetUserName (BYREF wszUrl AS CONST WSTRING) AS DWSTRING

Return value

If the function succeeds, it returns the user name; if it fails, it returns an empty string.

Usage example

FUNCTION AfxUrlGetUserName (BYREF wszUrl AS CONST WSTRING) AS DWSTRING

AfxUrlHash

Hashes a URL string.

FUNCTION AfxUrlHash (BYREF wszUrl AS WSTRING, BYVAL pbHash AS BYTE PTR, _
   BYVAL cbHash AS DWORD) AS HRESULT

Return value

If the function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

To hash a URL into a single byte, set cbHash = SIZEOF(BYTE) and pbHash = VARPTR(bHashedValue), where bHashedValue is a one-byte buffer.

To hash a URL into a DWORD, set cbHash = SIZEOF(DWORD) and pbHash = VARPTR(dwHashedValue), where dwHashedValue is a DWORD buffer.

AfxUrlIs

Tests whether or not a URL is a specified type.

FUNCTION AfxUrlIs (BYREF wszUrl AS WSTRING, BYVAL nUrlIs AS URLIS) AS BOOLEAN

Return value

For all but one of the URL types, AfxUrlIs returns True if the URL is the specified type, or False if not.

If AfxUrlIs is set to URLIS_APPLIABLE, AfxUrlIs will attempt to determine the URL scheme. If the function is able to determine a scheme, it returns True, or False otherwise.

AfxUrlIsFileUrl

Tests a URL to determine if it is a file URL.

FUNCTION AfxUrlIsFileUrl (BYREF wszUrl AS WSTRING) AS BOOLEAN

Return value

Returns True if the URL is a file URL, or False otherwise.

Remarks

A file URL has the form “File:// xxx”.

AfxUrlIsNoHistory

Returns whether a URL is a URL that browsers typically do not include in navigation history.

FUNCTION AfxUrlIsNoHistory (BYREF wszUrl AS CONST WSTRING) AS BOOLEAN

Return value

Returns a True value if the URL is a URL that is not included in navigation history, or False otherwise.

Remarks

This function is equivalent to the following: AfxUrlIs(wszURL, URLIS_NOHISTORY)

AfxUrlIsOpaque

Returns whether a URL is opaque.

FUNCTION AfxUrlIsOpaque (BYVAL wszUrl AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the URL is opaque, or False otherwise.

Remarks

A URL that has a scheme that is not followed by two slashes (//) is opaque. For example, mailto:xyz@litwareinc.com is an opaque URL. Opaque URLs cannot be separated into the standard URL hierarchy. AfxUrlIsOpaque is equivalent to the following: AfxUrlIs(wszURL, URLIS_OPAQUE)

AfxUrlUnescape

Converts escape sequences back into ordinary characters.

FUNCTION AfxUrlUnescape (BYREF wszUrl AS WSTRING, BYVAL dwFlags AS DWORD) AS DWSTRING

Return value

Returns S_OK (0) if successful or an HRESULT otherwise.

Remarks

An escape sequence has the form “%xy”.

Input strings cannot be longer than INTERNET_MAX_URL_LENGTH.

AfxUrlUnescapeInPlace

Converts escape sequences back into ordinary characters and overwrites the original string.

FUNCTION AfxUrlUnescapeInPlace (BYREF wszUrl AS WSTRING, BYVAL dwFlags AS DWORD) AS HRESULT

Return value

Returns S_OK (0) if successful or an HRESULT otherwise.